Installing External Objects

Introduction

These pages describe getting started with external objects, which you can use to extend the ExtendScript DOM and call into shared libraries of your own written in C/C++.

External objects are a key extensibility pattern for Adobe applications that integrate ExtendScript. You might want to use them to call into your own existing platform-native libraries or exploit the ability to call into C/C++ code of your own from a scripting context.

Installing a Compiled External Object

Step 1: Installing

The External Objects sample should compile and work with the libraries (DLLs or frameworks) in the locations that they are compiled to; this is where the sample JavaScript files provided expect the libraries to be located.

Once you have successfully compiled and tested the sample code with the provided sample scripts, you should be aware of the recommended deployment pattern for these extensions like your External Object library, which is effectively a plug-in. If you change the location of the libraries to this location, be sure to change the paths in JavaScript files that load the libraries accordingly.

The recommended location for extensions is different for each application so check their Programmer's Guide.

Step 2: Loading and Unloading

To load an external library from JavaScript, use the ExternalObject constructor:

 var myObj = new ExternalObject ("lib:" + libName);

The constructor can take an arbitrary number of arguments, which are passed on to the library's initialization routine:

 myObj = new ExternalObject ("lib:" + libName, arg1, arg2);

The specifier "lib:" is case sensitive. The library name can be the base name of the shared library as well as include the path to the library: Note: the ExternalObject architecture in future may be extended to wrap other types of external data; at present "lib:" is the marker for dynamically linked libraries.

  var libName = "C:\myLibraries\myLib.dll";
  var myObj = new ExternalObject ("lib:" + libName);

If the loader cannot load the library by its given name, it appends a file extension according to the operating system:

Windows: .DLL
Mac: .framework

If the library name does not contain a path specifier, but just the name of the library, then the loader first looks into the current folder for the library, which will be the application startup folder. If attaching the default extension does not work, the loader will then check the plug-ins folder within the program startup folder, Bridge for example would be:

Win - C:/Program Files/Adobe/Adobe Bridge CS3/Plug-Ins

Mac - /Applicationw/Adobe Bridge CS3/Plug-Ins

If you are following the recommendations above and using the chosen Application's Extensions directory, the library could be loaded as follows from a script executing from the root level of your "MyExtensions" folder, by writing:

  Folder.current = File ($.fileName).parent;
  var myLib = new ExternalObject("lib:Plugins/myLib.dll");

To unload a library, call the object's unload() method. This method unloads the library and leaves the object in an invalid state. Any attempts to access properties or methods of the library object once unloaded result in a runtime error.

  myLib.unload();

See Using the Sample Projects for information on how to find the sample projects

See Using the BasicExternalObject Sample for information on how to build the External Object sample

See Using the SampleLib Example for information on how to build the Sample Lib sample.